系列：從現場踩坑到 AI 工具 — IT Diagnostic Agent 開發實錄

「這應該很簡單」是一切踩坑的開始

把靜態 HTML 部署到 GitHub Pages，聽起來是最基本的事。

官方文件說：建一個 repo、把 HTML 推上去、Settings 裡開啟 Pages，就好了。

理論上是這樣。但我實際操作的時候，遇到了三個坑。

坑 1：master vs. main 的分支問題

這是最多人遇到的坑，但網路上的解說往往不夠清楚。

背景：
GitHub 在 2020 年之後，新建 repo 的預設主分支從 master 改成了 main。

但如果你的本地 Git 是舊版，或者你的 Git 全域設定沒有改，git init 建出來的分支還是叫 master。

問題發生的過程：

git init
git add .
git commit -m "first commit"
git remote add origin https://github.com/xxx/it-diagnostic-agent.git
git push origin master

Push 成功了，但去 GitHub 看，repo 裡有兩個分支：master（你剛推的）和 main（GitHub 自動建的空分支）。

然後你去 Settings → Pages，選 Source，下拉選單裡顯示 main（空的），你選了它，Pages 什麼都沒有。

解決方式：

方法一：強制推到 main

git push origin master:main --force

方法二：在 GitHub 上把預設分支改成 master，再設定 Pages 用 master

方法三：直接在 GitHub 網頁介面上傳檔案（最無腦但有效）

我最後常用的是方法一，因為它在 CLI 環境最快。

坑 2：GitHub Pages 的設定位置在 2024 年後移動了

舊文章說 Pages 設定在 Settings → Options → GitHub Pages。

但 GitHub 在 2023 年改版後，位置變成了 Settings → Pages（左側選單獨立一欄）。

這本身不是什麼大問題，但如果你照著舊文件找，會找不到，然後以為是 repo 設定有問題，浪費時間。

教訓： 官方文件永遠比部落格文章可信，尤其是 SaaS 平台的介面常常改。

坑 3：自訂網域的 CNAME 設定

這個坑不是每個人都會遇到，但我遇到了。

我一開始想用自訂網域，在 Pages 設定裡填了域名，GitHub 會自動在 repo 根目錄建一個 CNAME 檔案。

問題是：下次我 git push 之後，這個 CNAME 檔案被我的本地內容覆蓋掉了（因為我本地沒有這個檔案），Pages 的自訂網域設定就失效了。

解決方式：

先 git pull 把 GitHub 上的 CNAME 拉回來，合併到本地，再推。

或是在本地也建一個 CNAME 檔案，內容就是你的域名。

最後的部署方式

踩了這幾個坑之後，我建立了一套固定的部署流程：

初次部署

# 1. 本地初始化
git init
git add .
git commit -m "initial commit"

# 2. 連接遠端（先在 GitHub 建好空 repo）
git remote add origin https://github.com/USERNAME/REPO.git

# 3. 推到 main（不管本地叫什麼）
git push origin master:main

# 4. 去 GitHub Settings → Pages，選 main branch，儲存

後續更新

git add .
git commit -m "update: 說明這次改了什麼"
git push origin master:main

當 CLI 太麻煩的時候

直接在 GitHub 網頁介面用「Upload files」上傳或編輯檔案。

這對純靜態單檔工具非常實用，免去所有 Git 的麻煩，直接在瀏覽器裡改，改完 commit，Pages 幾分鐘內自動更新。

GitHub Pages 的限制要知道

部署成功之後，有幾個限制要注意：

1. 只支援靜態內容：不能執行 Server-side 程式碼（PHP、Python、Node.js 等）
2. 儲存庫大小限制：repo 建議不超過 1GB，Pages 網站不超過 1GB
3. 每月頻寬限制：100GB / 月（免費方案），對大多數工具來說夠用
4. 不能存儲敏感資料：API Key 不能放在程式碼裡（這是設計上的限制，不是壞事）

今天的反思

Git 和 GitHub 是現代 IT 工程師必備的工具，但它們的學習曲線比很多人想像的陡。

master vs. main 這個問題，至今還在困擾很多人，因為「新舊文件混用」是這個領域的常態。

保持版本意識，永遠先確認你用的是哪個版本的工具、對應哪個版本的文件。

這個習慣不只適用於 Git，適用於所有技術工具。

明天預告： 部署好了，使用者回饋說「看不懂英文」。雙語支援的需求浮現——但我不想用框架，那要怎麼在純 HTML/JS 裡實現 i18n？

作者：Rich Chang | IT 基礎建設工程師 | 越南・柬埔寨・台灣